Windows Procedures

Assorted Windows procedures.

Include File: AfxNova/AfxWin.inc.

Windows

File and Folder Procedures

Window

Window styles

Display

Messages

Handles

Common dialogs

High DPI

Fonts

Clipboard

Bitmap

Device Independent Bitmap (DIB)

Metric conversions

Mail and Internet

System information

Power status

AfxCommand

Returns command line parameters used to call the program. Unicode replacement for FreeBasic’s Command keyword. WCOmmand is an alias or AfxCommand.

FUNCTION AfxCommand (BYVAL nIndex AS LONG = -1) AS DWSTRING
#define WCommand AfxCommand

Return value

Returns the command-line arguments(s).

Remarks

AfxCommand returns command-line arguments passed to the program upon execution.

If index is less than zero (< 0), a space-separated list of all command-line arguments is returned, otherwise, a single argument is returned. A value of zero (0) returns the name of the executable; and values of one (1) and greater return each command-line argument.

If index is greater than the number of arguments passed to the program, a null string (““) is returned.

AfxCommandLineCount

Returns the number of command line arguments used to call the program. WCommandArgsc is an alias for AfxCommandLineCount.

FUNCTION AfxCommandLineCount (BYVAL nIndex AS LONG = -1) AS DWSTRING
#define WCommandArgsc AfxCommandLineCount

Return value

The number of command line arguments used to call the program.

AfxExtractResource

Extracts resource data and returns it as a string.

FUNCTION AfxExtractResource (BYVAL hInstance AS HINSTANCE, _
   BYREF wszResourceName AS WSTRING, BYVAL pResourceType AS LPWSTR = MAKEINTRESOURCEW(10)) AS STRING

Return value

A string containing the resource data.

Example

DIM strResData AS STRING = AfxExtractResource(NULL, "IDI_ARROW_RIGHT")
where IDI_ARROW_RIGHT is the identifier in the resource file for
IDI_ARROW_RIGHT RCDATA ".\Resources\arrow_right_64.png"
--or--
DIM strResData AS STRING = AfxExtractResource(NULL, "#111")
' where "#111" is the identifier in the resource file for
' 111 RCDATA ".\Resources\VEGA_PAZ_01.jpg"
-----
' // Write the resource data to a file
DIM hFile AS HANDLE = CreateFileW("PazVega.jpg", GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL)
IF hFile THEN
   DIM dwBytesWritten AS DWORD
   DIM bSuccess AS BOOLEAN = WriteFile(hFile, STRPTR(strResData), LEN(strResData), @dwBytesWritten, NULL)
   CloseHandle(hFile)
   print bSuccess
END IF

AfxExtractResourceToFile

Extracts resource data and saves it to a file.

FUNCTION AfxExtractResourceToFile (BYVAL hInstance AS HINSTANCE, BYREF wszResourceName AS WSTRING, _
   BYREF wszFileName AS WSTRING, BYVAL pResourceType AS LPWSTR = MAKEINTRESOURCEW(10)) AS STRING

Return value

TRUE on success of FALSE on failure.

Example

AfxExtractResourceToFile(NULL, "IDI_ARROW_RIGHT", "IDI_ARROW_RIGHT.png")
where IDI_ARROW_RIGHT is the identifier in the resource file for
IDI_ARROW_RIGHT RCDATA ".\Resources\arrow_right_64.png"

Example

AfxExtractResourceToFile(NULL, "#111", "VEGA_PAZ_01.jpg")
where "#111" is the identifier in the resource file for
111 RCDATA ".\Resources\VEGA_PAZ_01.jpg"

AfxChDir

Changes the current directory for the current process. Aliases: AfxSetCurDir, AfxSetCurrentDirectory.

FUNCTION AfxChDir (BYVAL pwszPathName AS LPCWSTR) AS LONG
FUNCTION AfxSetCurDir (BYVAL pwszPathName AS LPCWSTR) AS BOOLEAN
FUNCTION AfxSetCurrentDirectory (BYVAL pwszPathName AS LPCWSTR) AS BOOLEAN

Return value for AfxChDir:

If the function succeeds, the return value is 0.
If the function fails, the return value is -1.
To get extended error information, call GetLastError.

AfxMkDir is an unicode replacement for Free Basic’s MkDir.

Return value for AfxSetCurDir and AfxSetCurrentDirectory:

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE.
To get extended error information, call GetLastError.

AfxCopyFile

Copies an existing file to a new file. Alias: AfxFileCopy.

FUNCTION AfxCopyFile (BYVAL lpExistingFileName AS LPCWSTR, BYVAL lpNewFileName AS LPCWSTR, _
   BYVAL bFailIfExists AS BOOLEAN = FALSE) AS BOOLEAN
FUNCTION AfxFileCopy (BYVAL lpExistingFileName AS LPCWSTR, BYVAL lpNewFileName AS LPCWSTR, _
   BYVAL bFailIfExists AS BOOLEAN = FALSE) AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Rermarks

AfxFileCopy is an unicode replacement for Free Basic’s FileCopy and returns 0 on success, or 1 if an error occurred.

AfxMkDir

Creates a new directory. Aliases: AfxMakeDir, AfxCreateDirectory.

FUNCTION AfxMkDir (BYVAL lpPathName AS LPCWSTR) AS LONG
FUNCTION AfxCreateDirectory (BYVAL lpPathName AS LPCWSTR) AS BOOLEAN
FUNCTION AfxMakeDir (BYVAL lpPathName AS LPCWSTR) AS BOOLEAN

Return value for AfxMkDir:

If the function succeeds, the return value is 0.
If the function fails, the return value is -1.
To get extended error information, call GetLastError.

AfxMkDir is an unicode replacement for Free Basic’s MkDir.

Return value for AfxCreateDirectory and AfxMakeDir:

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE.
To get extended error information, call GetLastError.

Possible errors include the following.

AfxDeleteFile

Deletes the specified file. Alias: AfxKill.

FUNCTION AfxDeleteFile (BYVAL pwszFileSpec AS WSTRING PTR) AS BOOLEAN
FUNCTION AfxKill (BYVAL pwszFileSpec AS WSTRING PTR) AS BOOLEAN

Return value:

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE.
To get extended error information, call GetLastError.

Remarks

If an application attempts to delete a file that does not exist, this function fails with ERROR_FILE_NOT_FOUND. If the file is a read-only file, the function fails with ERROR_ACCESS_DENIED.

AfxKill is an unicode replacement for Free Basic’s Kill and returns 0 on success, or -1 on failure.

AfxFileDateTime

Returns the file’s last modified date and time as Date Serial. Unicode replacement for Free Basic’s FileDateTime.

FUNCTION AfxFileDateTime (BYREF wszFileName AS WSTRING) AS DOUBLE

Return value

The date and time as a Date Serial. If it fails, it returns 0.

Example

#include "windows.bi"
#include "vbcompat.bi"
#include "Afx/AfxWin.bi"
DIM wszFileName AS WSTRING * MAX_PATH = ExePath & "\c2.bas"
DIM dt AS DOUBLE = AfxFileDateTime(wszFileName)
PRINT Format(dt, "yyyy-mm-dd hh:mm AM/PM")

AfxCurdir

Retrieves the current directory for the current process. Aliases: AfxGetCurDir, AfxGetCurrentDirectory- Unicode replacement for Free Basic’s CurDir.

FUNCTION AfxCurDir () AS DWSTRING
FUNCTION AfxGetCurDir () AS DWSTRING
FUNCTION AfxGetCurrentDirectory () AS DWSTRING

Return value

The name of the current directory for the current process.

AfxMoveFile

Moves an existing file or a directory, including its children. Aliases: AfxRenameFile, AfxMoveFile. AfxName is an unicode replacement for Free Basic’s Name.

FUNCTION AfxName (BYVAL lpExistingFileName AS LPCWSTR, BYVAL lpNewFileName AS LPCWSTR) AS LONG
FUNCTION AfxRenameFile (BYVAL lpExistingFileName AS LPCWSTR, BYVAL lpNewFileName AS LPCWSTR) AS BOOLEAN
FUNCTION AfxMoveFile (BYVAL lpExistingFileName AS LPCWSTR, BYVAL lpNewFileName AS LPCWSTR) AS BOOLEAN

Return value for AfxName:

If the function succeeds, the return value is 0.
If the function fails, the return value is -1.
To get extended error information, call GetLastError.

AfxName is an unicode replacement for Free Basic’s Name.

Return value for AfxRenameFile and AfxMoveFile:

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE.
To get extended error information, call GetLastError.

AfxRemoveDir

Deletes an existing empty directory. Aliases: AfxRemoveDirectory. AfxRmDir is an unicode replacement for Free Basic’s RmDir.

FUNCTION AfxRmDir (BYVAL lpPathName AS LPCWSTR) AS LONG
FUNCTION AfxRemoveDir (BYVAL lpPathName AS LPCWSTR) AS BOOLEAN
FUNCTION AfxRemoveDirectory (BYVAL lpPathName AS LPCWSTR) AS BOOLEAN

Return value for AfxRmDir:

If the function succeeds, the return value is 0.
If the function fails, the return value is -1.
To get extended error information, call GetLastError.

AfxRmDir is an unicode replacement for Free Basic’s RmDir.

Return value for AfxRemoveDir and AfxRemoveDirectory:

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE.
To get extended error information, call GetLastError.

Remaks

These functions mark a directory for deletion on close. Therefore, the directory is not removed until the last handle to the directory is closed. To recursively delete the files in a directory, use the SHFileOperation function.

AfxFileExists

Searches a directory for a file or subdirectory with a name that matches a specific name (or partial name if wildcards are used).

FUNCTION AfxFileExists (BYVAL pwszFileSpec AS WSTRING PTR) AS BOOLEAN

Return value

Boolean. TRUE if the specified file exist or FALSE otherwise.

Remarks

Prepending the string “\\?\” does not allow access to the root directory.

On network shares, you can use an pwszFileSpec in the form of the following: “\\server\*”. However, you cannot use an pwszFileSpec that points to the share itself; for example, “\\server” is not valid.

To examine a directory that is not a root directory, use the path to that directory, without a trailing backslash. For example, an argument of “C:” returns information about the directory “C:”, not about a directory or file in “C:”. To examine the files and directories in “C:”, use an pwszFileSpec of “C:*”.

Be aware that some other thread or process could create or delete a file with this name between the time you query for the result and the time you act on the information. If this is a potential concern for your application, one possible solution is to use the CreateFile function with CREATE_NEW (which fails if the file exists) or OPEN_EXISTING (which fails if the file does not exist).

AfxFolderExists

Searches a directory for a file or subdirectory with a name that matches a specific name (or partial name if wildcards are used).

FUNCTION AfxFolderExists (BYVAL pwszFileSpec AS WSTRING PTR) AS BOOLEAN

Return value

Boolean. TRUE if the specified file exist or FALSE otherwise.

Remarks

Prepending the string “\\?\” does not allow access to the root directory.

On network shares, you can use an pwszFileSpec in the form of the following: “\\server\*”. However, you cannot use an pwszFileSpec that points to the share itself; for example, “\\server” is not valid.

To examine a directory that is not a root directory, use the path to that directory, without a trailing backslash. For example, an argument of “C:” returns information about the directory “C:”, not about a directory or file in “C:”. To examine the files and directories in “C:”, use an pwszFileSpec of “C:\*”.

Be aware that some other thread or process could create or delete a file with this name between the time you query for the result and the time you act on the information. If this is a potential concern for your application, one possible solution is to use the CreateFile function with CREATE_NEW (which fails if the file exists) or OPEN_EXISTING (which fails if the file does not exist).

AfxGetFileSize

Returns the size in bytes of the specified file. Alias: AfxFileLen.

FUNCTION AfxGetFileSize (BYREF wszFileSpec AS WSTRING) AS ULONGLONG
FUNCTION AfxFileLen (BYREF wszFileSpec AS WSTRING) AS ULONGLONG

Return value

The size in bytes of the file on success, or 0 on failure.

AfxExePath

Returns the path of the program which is currently executing.

FUNCTION AfxExePath () AS DWSTRING
FUNCTION AfxGetExePath () AS DWSTRING

Remarks

Unicode replacement for Free Basic’s ExePath function. The path name has not a trailing backslash, except if it is a drive, e.g. “C:".

Alias

AfxGetExePath.

AfxGetExePathName

Returns the path of the program which is currently executing.

FUNCTION AfxGetExePathName () AS DWSTRING

Remarks

The path name has a trailing backslash.

Alias

AfxExePathName

AfxGetDriveType

Determines whether a disk drive is a removable, fixed, CD-ROM, RAM disk, or network drive.

FUNCTION AfxGetDriveType (BYVAL lpRootPathName AS LPCWSTR) as UINT

Return value

DRIVE_UNKNOWN (0), DRIVE_NO_ROOT_DIR (1), DRIVE_REMOVABLE (2), DRIVE_FIXED(3), DRIVE_REMOTE (4), DRIVE_CDROM (5), DRIVE_RAMDISK (6).

AfxGetExeFileExt

Parses a path/filename and returns the extension portion of the path/file name.

FUNCTION AfxGetExeFileExt () AS DWSTRING

Return value

The extension portion of the file name. That is the last period (.) in the string plus the text to the right of it.

Alias

AfxExeFileExt

AfxGetExeFileName

Returns the file name of the program which is currently executing.

FUNCTION AfxGetExeFileName () AS DWSTRING

Alias

** AfxExeFilename**

AfxGetExeFileNameX

Returns the file name and extension of the program which is currently executing.

FUNCTION AfxGetExeFileNameX () AS DWSTRING

Alias

** AfxExeFilenameX**

AfxGetExeFullPath

Returns the complete drive, path, file name, and extension of the program which is currently executing.

FUNCTION AfxGetExeFullPath () AS DWSTRING

Alias

AfxExeFullPath

AfxGetFileExt

Parses a path/filename and returns the extension portion of the path/file name. That is the last period (.) in the string plus the text to the right of it.

FUNCTION AfxGetFileExt (BYREF wszPath AS WSTRING) AS DWSTRING

Alias

AfxFileExt

AfxGetFileCreationTime

Returns the time the file was created, in FILETIME format.

FUNCTION AfxGetFileCreationTime (BYREF wszFileSpec AS WSTRING, BYVAL bUTC AS BOOLEAN = TRUE) AS FILETIME

AfxGetFileLastAccessTime

Returns the time the file was accessed, in FILETIME format.

FUNCTION AfxGetFileLastAccessTime (BYREF wszFileSpec AS WSTRING, BYVAL bUTC AS BOOLEAN = TRUE) AS FILETIME

AfxGetFileLastWriteTime

Returns the time the file was last written to, truncated, or overwritten, in FILETIME format.

FUNCTION AfxGetFileLastWriteTime (BYREF wszFileSpec AS WSTRING, BYVAL bUTC AS BOOLEAN = TRUE) AS FILETIME

AfxGetFileName

Parses a path/filename and returns the file name portion. That is the text to the right of the last backslash () or colon (:), ending just before the last period (.).

FUNCTION AfxGetFileName (BYREF wszPath AS WSTRING) AS DWSTRING

Alias

AfxFileName

AfxGetFileNameX

Parses a path/filename and returns the file name and extension portion. That is the text to the right of the last backslash (\) or colon (:).

FUNCTION AfxGetFileNameX (BYREF wszPath AS WSTRING) AS DWSTRING

Alias

AfxFileNameX

AfxGetFileVersion

Retrieves the version of the specified file multiplied by 100, e.g. 601 for version 6.01.

FUNCTION AfxGetFileVersion (BYVAL pwszFileName AS WSTRING PTR) AS DWORD

AfxGetFolderName

Returns a string containing the name of the folder for a specified path, i.e. the path minus the file name.

FUNCTION AfxGetFolderName (BYREF wszPath AS WSTRING) AS DWSTRING

Alias

AfxGetFolderName

AfxGetKnowFolderPath

Retrieves the path of an special folder.

FUNCTION AfxGetKnowFolderPath (BYVAL rfid AS CONST KNOWNFOLDERID CONST PTR, _
   BYVAL dwFlags AS DWORD = 0, BYVAL hToken AS HANDLE = NULL) AS DWSTRING

Return value

The path of the requested folder on success, or an empty string on failure.

Remarks

Requires Windows Vista/Windows 7 or superior.

For a list of KNOWNFOLDERID constants see: KNOWNFOLDERID

Usage example

AfxGetKnowFolderPath(@FOLDERID_CommonPrograms)

AfxGetLongPathName

Retrieves the short path form of the specified path.

FUNCTION AfxGetLongPathName (BYREF wszPath AS WSTRING) AS DWSTRING

Alias

AfxLongPathName

AfxGetPathFromProcessId

Retrieves the path of the executable file given its process identifier.

FUNCTION AfxGetPathFromProcessId (BYVAL dwProcessId AS DWORD) AS DWSTRING

Alias

AfxPathFromProcessId

AfxGetPathName

Parses a path/filename and returns the path portion. That is the text up to and including the last backslash () or colon (:).

FUNCTION AfxGetPathName (BYREF wszPath AS WSTRING) AS DWSTRING

Alias

AfxPathName

AfxGetShortPathName

Retrieves the short path form of the specified path.

FUNCTION AfxGetShortPathName (BYREF wszPath AS WSTRING) AS DWSTRING

Alias

AfxShortPathName

AfxGetSpecialFolderLocation

Retrieves the path of a special folder.

FUNCTION AfxGetSpecialFolderLocation (BYVAL nFolder AS LONG) AS DWSTRING

Remarks

For a list of CSIDL values see: CSIDL

AfxGetSystemDllPath

Retrieves the fully qualified path for the file that contains the specified module.

FUNCTION AfxGetSystemDllPath (BYREF wszDllName AS WSTRING) AS DWSTRING

Remarks

To locate the file for a module that was loaded by another process, use the GetModuleFileNameEx function.

Alias

AfxSystemDllPath

AfxSystemDrive

Returns the system drive name, e.g. “C:”.

FUNCTION AfxSystemDrive () AS DWSTRING

Alias

AfxGetSystemDrive

AfxSystemDirectory

Retrieves the path of the system directory.

FUNCTION AfxSystemDirectory () AS DWSTRING

Alias

AfxGetSystemDirectory

AfxGetWinDir

Retrieves the path of the Windows directory. This path does not end with a backslash unless the Windows directory is the root directory. For example, if the Windows directory is named Windows on drive C, the path of the Windows directory retrieved by this function is C:. If the system was installed in the root directory of drive C, the path retrieved is C:\.

FUNCTION AfxGetWinDir () AS DWSTRING

Aliases

AfxWindir, “AfxWindowsDirectory

GetTempPath

Retrieves the path of the directory designated for temporary files.

FUNCTION AfxGetTempPath () AS DWSTRING

Alias

AfxTempPath

AfxGetSystemWow64Directory

Retrieves the path of the system directory used by WOW64. This directory is not present on 32-bit Windows.

FUNCTION AfxGetSystemWow64Directory () AS DWSTRING

Alias

AfxSystemWow64Directory

AfxIsCompressedFile

Returns True if the specified file or directory is compressed; False if it is not.

FUNCTION AfxIsCompressedFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsEncryptedFile

Returns True if the specified file or directory is encrypted; False if it is not.

FUNCTION AfxIsEncryptedFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsFolder

Returns True if the specified path is a folder; False if it is not.

FUNCTION AfxIsFolder (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsHiddenFile

Returns True if the specified path is a hidden file or directory; False if it is not.

FUNCTION AfxIsHiddenFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsNormalFile

Returns True if the specified path is a normal file (a file that does not have other attributes set); False if it is not.

FUNCTION AfxIsNormalFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsNotContentIndexedFile

Returns TRUE if the specified file or directory is not to be indexed by the content indexing service; FALSE, otherwise.

FUNCTION AfxIsNotContentIndexedFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsOfflineFile

Returns TRUE if the specified file file is not available immediately; FALSE, otherwise.

FUNCTION AfxIsOfflineFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsReadOnlyFile

Returns True if the specified path is a read only file; False if it is not.

FUNCTION AfxIsReadOnlyFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsReparsePointFile

Returns TRUE if the specified path is a file or directory that has an associated reparse point, or a file that is a symbolic link.; FALSE, otherwise.

FUNCTION AfxIsReparsePointFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsSparseFile

Returns TRUE if the specified path is a sparse file; FALSE, otherwise.

FUNCTION AfxIsSparseFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsSystemFile

Returns True if the specified path is a system file; False if it is not.

FUNCTION AfxIsSystemFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsTemporaryFile

Returns True if the specified path is a temporary file; False if it is not.

FUNCTION AfxIsTemporaryFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxFileScan

Scans a text file ans returns the number of occurrences of the specified delimiter.

FUNCTION AfxFileScanA (BYREF wszFileName AS WSTRING, BYREF Delimiter AS ZSTRING = CHR(13, 10)) AS DWORD
FUNCTION AfxFileScanW (BYREF wszFileName AS WSTRING, BYREF Delimiter AS WSTRING = CHR(13, 10)) AS DWORD

Remarks

Use AfxFileScanA for ansi text files and AfxFileScanW for unicode text files.

AfxFileReadAllLines

Reads all the lines of the specified file into a safe array.

FUNCTION AfxFileReadAllLinesA (BYREF wszFileName AS WSTRING, BYREF Delimiter AS ZSTRING = CHR(13, 10)) AS DSafeArray
FUNCTION AfxFileReadAllLinesW (BYREF wszFileName AS WSTRING, BYREF Delimiter AS WSTRING = CHR(13, 10)) AS DSafeArray

Remarks

Use AfxFileReadAllLinesA for ansi text files and AfxFileReadAllLinesW for unicode text files.

Because it returns a safe array, this function is located in the DSafeArray.inc include file.

AfxSaveIconToFile

Saves an icon to a file.

FUNCTION AfxSaveIconToFile (BYVAL hIcon AS HICON, BYREF fileName AS WSTRING) AS HRESULT

Return value

Returns S_OK on success or and HRESULT code on failure.

Usage examples

DIM hIcon as HICON = LoadIcon(NULL, IDI_INFORMATION)
DIM hr AS HRESULT = AfxSaveIconToFile(hIcon, "test.ico")

DIM hIcon AS HICON = cast(HICON, LoadImage(NULL, ExePath & "\" & "MyIco.ico", IMAGE_ICON, 32, 32, LR_LOADFROMFILE))
DIM hr AS HRESULT = AfxSaveIconToFile(hIcon, "test2.ico")

AfxSaveTempFile

Saves the contents of a string buffer in a temporary file.

FUNCTION AfxSaveTempFile (BYVAL pwszBuffer AS WSTRING PTR, BYREF wszExtension AS WSTRING) AS DWSTRING

Remarks

Temporary files whose names have been created by this function are not automatically deleted. To delete these files call AfxDeleteFile.

AfxAddWindowExStyle

Adds a new extended style to the specified window.

FUNCTION AfxAddWindowExStyle (BYVAL hwnd AS HWND, BYVAL dwExStyle AS DWORD) AS DWORD

Return value

The previous window extended styles.

Usage example

AfxAddWindowExStyle(hwnd, WS_EX_COMPOSITED)

Remarks

If the window has a class style of CS_CLASSDC or CS_OWNDC, do not set the extended window styles WS_EX_COMPOSITED or WS_EX_LAYERED.

AfxAddWindowStyle

Adds a new style to the specified window.

FUNCTION AfxAddWindowStyle (BYVAL hwnd AS HWND, BYVAL dwStyle AS DWORD) AS DWORD

Return value

The previous window styles.

Usage example

AfxAddWindowStyle(hwnd, WS_HSCROLL)

AfxGetWindowExStyle

Retrieves the extended window styles.

FUNCTION AfxGetWindowExStyle (BYVAL hwnd AS HWND) AS DWORD

AfxGetWindowStyle

Retrieves the window styles.

FUNCTION AfxGetWindowStyle (BYVAL hwnd AS HWND) AS DWORD

AfxRemoveWindowExStyle

Removes an extended style from the specified window.

FUNCTION AfxRemoveWindowExStyle (BYVAL hwnd AS HWND, BYVAL dwExStyle AS DWORD) AS DWORD

Return value

The previous extended window styles.

AfxRemoveWindowStyle

Removes a style from the specified window.

FUNCTION AfxRemoveWindowStyle (BYVAL hwnd AS HWND, BYVAL dwStyle AS DWORD) AS DWORD

Return value

The previous window styles.

AfxSetWindowExStyle

Sets the extended style(s) of the specified window.

FUNCTION AfxSetWindowExStyle (BYVAL hwnd AS HWND, BYVAL dwExStyle AS DWORD) AS DWORD

Return value

The previous extended window styles.

AfxSetWindowStyle

Sets the style(s) of the specified window.

FUNCTION AfxSetWindowStyle (BYVAL hwnd AS HWND, BYVAL dwStyle AS DWORD) AS DWORD

Return value

The previous window styles.

AfxForceVisibleDisplay

If you use dual (or even triple/quad) displays then you have undoubtedly encountered the following situation: You change the physical order of your displays, or otherwise reconfigure the logical ordering using your display software. This sometimes has the side-effect of changing your desktop coordinates from zero-based to negative starting coordinates (i.e. the top-left coordinate of your desktop changes from 0,0 to -1024,-768).

This effects many Windows programs which restore their last on-screen position whenever they are started. Should the user reorder their display configuration this can sometimes result in a Windows program subsequently starting in an off-screen position (i.e. at a location that used to be visible) - and is now effectively invisible, preventing the user from closing it down or otherwise moving it back on-screen.

The AfxForceVisibleDisplay function can be called at program start-time right after the main window has been created and positioned ‘on-screen’. Should the window be positioned in an off-screen position, it is forced back onto the nearest display to its last position. The user will be unaware this is happening and won’t even realize to thank you for keeping their user-interface visible, even though they changed their display settings.

Source: Catch-22 web site.

SUB AfxForceVisibleDisplay (BYVAL hwnd AS HWND)

AfxGetDisplayBitsPerPixel

Returns the color resolution, in bits per pixel, of the display device.

FUNCTION AfxGetDisplayBitsPerPixel () AS DWORD

Aliases

AfxScreenColors, AfxGetScreenColors

AfxGetDisplayFrequency

Returns the frequency, in hertz (cycles per second), of the display device in a particular mode. This value is also known as the display device’s vertical refresh rate.

FUNCTION AfxGetDisplayBitsPerPixel () AS DWORD

Aliases

AfxGetScreenRefreshDate, AfxScreenRefreshDate

AfxGetDisplayPixelsHeight

Returns the height, in pixels, of the current display device on the computer on which the calling thread is running.

FUNCTION AfxGetDisplayPixelsHeight () AS DWORD

AfxGetDisplayPixelsWidth

Returns the width, in pixels, of the current display device on the computer on which the calling thread is running.

FUNCTION AfxGetDisplayPixelsWidth () AS DWORD

Remarks

Contrarily to GetSystemMetrics or GetDeviceCaps, it returns the real width even when it is called from an application that is not DPI aware, e.g. an application running virtualized in a monitor 1920 pixels width and a DPI of 192, will return 960 pixels if it calls GetSystemMetrics or GetDeviceCaps, but will return 1920 pixels calling AfxGetDisplayPixelsWidth.

AfxScreenHeight

Retrieves the height of the screen, in pixels. This function is virtualized for DPI.

FUNCTION AfxGetScreenHeight () AS LONG

Alias

AfxGetScreenHeight

AfxScreenWidth

Retrieves the width of the screen, in pixels. This function is virtualized for DPI.

FUNCTION AfxScreenWidth () AS LONG

Alias

AfxGetScreenWidth

AfxGetWorkArea

Retrieves the coordinates of the work area on the primary display monitor expressed in virtual screen coordinates. The work area is the portion of the screen not obscured by the system taskbar or by application desktop toolbars. To get the work area of a monitor other than the primary display monitor, call the GetMonitorInfo function.

FUNCTION AfxGetWorkArea () AS RECT

Alias

AfxWorkArea

AfxDoEvents

Processes pending Windows messages. Call this procedure if you are performing a tight FOR/NEXT or DO/LOOP and need to allow your application to be responsive to user input.

SUB AfxDoEvents (BYVAL hWin AS HWND = NULL)

AfxForwardSizeMessage

Sends a WM_SIZE message to the specified window.

FUNCTION AfxForwardSizeMessage (BYVAL hwnd AS HWND, BYVAL nResizeType AS DWORD, _
   BYVAL nWidth AS LONG, BYVAL nHeight AS LONG) AS LRESULT

Remark

If an application processes this message, it should return zero.

AfxPumpMessages

Processes pending Windows messages. Call this procedure if you are performing a tight FOR/NEXT or DO/LOOP and need to allow your application to be responsive to user input.

SUB AfxPumpMessages

AfxGetControlHandle

Returns the handle of the control with the specified identifier. The reference handle can be the handle of the form or the handle of any other control on the form.

FUNCTION AfxGetControlHandle (BYVAL hwnd AS HWND, BYVAL wCtrlID AS WORD) AS HWND

Return value

Returns the handle of the control or NULL.

AfxGetFormHandle

Finds the handle of the top-level window or MDI child window that is the ancestor of the specified window handle. The reference handle is the handle of any control on the form.

FUNCTION AfxGetFormHandle (BYVAL hwnd AS HWND) AS HWND

Return value

Handle of the ancestor window.

AfxGetHwndFromPID

Retrieves a window handle given it’s process identifier.

FUNCTION AfxGetHwndFromPID (BYVAL PID AS DWORD) AS HWND

Return value

The window handle or NULL.

AfxGetPathFromWindowHandle

Retrieves the path of the executable file that created the specified window.

FUNCTION AfxGetPathFromWindowHandle (BYVAL hwnd AS HWND) AS DWSTRING

Return value

The path of the executable file.

Alias

AfxPathFromWindowHandle

AfxBrowseForFolder

Displays a dialog box that enables the user to select a folder.

FUNCTION AfxBrowseForFolder (BYVAL hwnd AS HWND, BYVAL pwszTitle AS WSTRING PTR = NULL, _
   BYVAL pwszStartFolder AS WSTRING PTR = NULL, BYVAL nFlags AS LONG = 0) AS DWSTRING

Notes

If COM is initialized through CoInitializeEx with the COINIT_MULTITHREADED flag set, AfxShellBrowserForFolder fails if BIF_NEWDIALOGSTYLE or BIF_USENEWUI are passed.

Return value

The path of the selected folder.

Remarks

If you don’t pass any flags, the function will use BIF_RETURNONLYFSDIRS OR BIF_DONTGOBELOWDOMAIN OR BIF_USENEWUI OR BIF_RETURNFSANCESTORS.

Usage example

DIM dws AS DWSTRING = AfxBrowseForFolder(hwnd, "C:")

AfxChooseColorDialog

Displays the Windows choose color dialog.

FUNCTION AfxChooseColorDialog (BYVAL hwnd AS HWND, BYVAL rgbDefaultColor AS COLORREF = 0, _
   BYVAL lpCustColors AS COLORREF PTR = NULL) AS LONG

Return value

The selected color, or -1 if the user has canceled the dialog.

AfxControlRunDLL

Control_RunDLL is an undocumented procedure in the Shell32.dll which can be used to launch control panel applications. You’ve to pass the name of the control panel file (.cpl) and the tool represented by it will be launched. For launching some control panel applications, you’ve to provide a valid windows handle (hwnd parameter) and program instance (hInst) parameter).

FUNCTION AfxControlRunDLL (BYVAL hwnd AS HWND, BYVAL hInst AS HINSTANCE, _
   BYVAL cmd AS WSTRING PTR, BYVAL nCmdShow AS LONG) AS BOOLEAN

Usage examples

AfxControlRunDLL(0, 0, "", SW_SHOWNORMAL)   ' Opens the control panel
AfxControlRunDLL(0, 0, "appwiz.cpl", SW_SHOWNORMAL)   ' Opens the applications wizard

AfxOpenFileDialog

Creates an Open dialog box that lets the user specify the drive, directory, and the name of a file or set of files to be opened. The dialog box uses the Explorer-style user interface.

FUNCTION AfxOpenFileDialog (BYVAL hwndOwner AS HWND, BYREF wszTitle AS WSTRING, BYREF wszFile AS WSTRING, _
   BYREF wszInitialDir AS WSTRING, BYREF wszFilter AS WSTRING, BYREF wszDefExt AS WSTRING, _
   BYVAL pdwFlags AS DWORD PTR = NULL, BYVAL pdwBufLen AS DWORD PTR = NULL) AS DWSTRING

Return value

If the OFN_ALLOWMULTISELECT flag is set and the user selects multiple files, the returned string contains the current directory followed by the file names of the selected files. For Explorer-style dialog boxes, the directory and file name strings are separated by semicolons. If the user selects only one file, the returned string does not have a separator between the path and file name.

Parse the number of “,”. If only one, then the user has selected only a file and the string contains the full path. If more, The first substring contains the path and the others the files. If the user has not selected any file, an empty string is returned. On failure, an empty string is returned and, if not null, the pdwBufLen parameter will be filled by the size of the required buffer in characters.

Usage example:

DIM wszFile AS WSTRING * 260 = "*.*"
DIM wszInitialDir AS STRING * 260 = CURDIR
DIM wszFilter AS WSTRING * 260 = "BAS files (*.BAS)|*.BAS|" & "All Files (*.*)|*.*|"
DIM dwFlags AS DWORD = OFN_EXPLORER OR OFN_FILEMUSTEXIST OR OFN_HIDEREADONLY OR OFN_ALLOWMULTISELECT
DIM dws AS DWSTRING = AfxOpenFileDialog(hwnd, "", wszFile, wszInitialDir, wszFilter, "BAS", @dwFlags, NULL)

AfxSaveFileDialog

Creates a Save dialog box that lets the user specify the drive, directory, and name of a file to save. The dialog box uses the Explorer-style user interface.

FUNCTION AfxSaveFileDialog (BYVAL hwndOwner AS HWND, BYREF wszTitle AS WSTRING, BYREF wszFile AS WSTRING, _
   BYREF wszInitialDir AS WSTRING, BYREF wszFilter AS WSTRING, BYREF wszDefExt AS WSTRING, _
   BYVAL pdwFlags AS DWORD PTR = NULL) AS DWSTRING

Return value

The path of the file to be saved.

Usage example:

DIM wszFile AS WSTRING * 260 = "*.*"
DIM wszInitialDir AS STRING * 260 = CURDIR
DIM wszFilter AS WSTRING * 260 = "BAS files (*.BAS)|*.BAS|" & "All Files (*.*)|*.*|"
DIM dwFlags AS DWORD = OFN_EXPLORER OR OFN_FILEMUSTEXIST OR OFN_HIDEREADONLY OR OFN_OVERWRITEPROMPT
DIM dws AS DWSTRING = AfxSaveFileDialog(hwnd, "", wszFile, wszInitialDir, wszFilter, "BAS", @dwFlags)

AfxShowSysInfo

Displays the Windows Information System dialog.

FUNCTION AfxShowSysInfo (BYVAL hwnd AS HWND) AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

AfxGetMonitorHorizontalScaling

Returns the horizontal scaling of the monitor that the window is currently displayed on.

FUNCTION AfxGetMonitorHorizontalScaling (BYVAL hwnd AS HWND = NULL) AS DWORD

Remarks

If the application to which the window belongs is not DPI aware, a computer using 192 DPI, will return an scaling ratio of 2.

AfxGetMonitorVerticalScaling

Returns the vertical scaling of the monitor that the window is currently displayed on.

FUNCTION AfxGetMonitorVerticalScaling (BYVAL hwnd AS HWND = NULL) AS DWORD

Remarks

If the application to which the window belongs is not DPI aware, a computer using 192 DPI, will return an scaling ratio of 2.

AfxGetMonitorLogicalHeight

Returns the logical height of the monitor that the window is currently displayed on.

FUNCTION AfxGetMonitorLogicalHeight (BYVAL hwnd AS HWND = NULL) AS DWORD

Remarks

If the application to which the window belongs is not DPI aware, a monitor with an height resolution of 1080 pixels in a computer using 192 DPI, will return 540 pixels.

AfxGetMonitorLogicalWidth

Returns the logical width of the monitor that the window is currently displayed on.

FUNCTION AfxGetMonitorLogicalWidth (BYVAL hwnd AS HWND = NULL) AS DWORD

Remarks

If the application to which the window belongs is not DPI aware, a monitor with a width resolution of 1920 pixels in a computer using 192 DPI, will return 960 pixels.

AfxIsDPIResolutionAtLeast

Determines if screen resolution meets minimum requirements in relative pixels, e.g. for a screen resolution of 1920x1080 pixels and a DPI of 192 (scaling ratio = 2), the maximum relative pixels for a DPI aware application is 960x540.

FUNCTION AfxIsDPIResolutionAtLeast (BYVAL cxMin AS LONG, BYVAL cyMin AS LONG) AS BOOLEAN

Return value

TRUE or FALSE.

AfxIsProcessDPIAware

Determines whether the current process is dots per inch (dpi) aware such that it adjusts the sizes of UI elements to compensate for the dpi setting.

FUNCTION AfxIsProcessDPIAware () AS BOOLEAN

Return value

TRUE if the process is dpi aware; otherwise, FALSE.

AfxIsResolutionAtLeast

Determines if screen resolution meets minimum requirements.

FUNCTION AfxIsResolutionAtLeast (BYVAL cxMin AS LONG, BYVAL cyMin AS LONG) AS BOOLEAN

Return value

TRUE or FALSE.

AfxLoadIconMetric

Loads a specified icon resource with a client-specified system metric.

FUNCTION AfxLoadIconMetric (BYVAL hinst AS HINSTANCE, BYVAL pwszName AS WSTRING PTR, _
   BYVAL lims AS LONG, BYVAL phico AS HICON PTR) AS HRESULT

Return value

Returns S_OK if successful, otherwise an error, including the following value: E_INVALIDARG : The contents of the buffer pointed to by pszName do not fit any of the expected interpretations.

Remarks

LoadIconMetric is similar to LoadIcon, but with the capability to specify the icon metric. It is used in place of LoadIcon when the calling application wants to ensure a high quality icon. This is particularly useful in high dots per inch (dpi) situations.

Icons are extracted or created as follows.

1. If an exact size match is found in the resource, that icon is used.
   
2. If an exact size match cannot be found and a larger icon is available, a new icon is created by scaling the larger version down to the desired size.
   
3. If an exact size match cannot be found and no larger icon is available, a new icon is created by scaling a smaller icon up to the desired size.

AfxLogPixelsX

Retrieves the number of pixels per logical inch along the screen width. In a system with multiple display monitors, this value is the same for all monitors. Aliases: AfxGetDpi, AfxGetDpiX.

FUNCTION AfxLogPixelsX () AS LONG
FUNCTION AfxGetDpi () AS LONG
FUNCTION AfxGetDpiX () AS LONG

AfxLogPixelsY

Retrieves the number of pixels per logical inch along the screen height. In a system with multiple display monitors, this value is the same for all monitors. Alias: AfxGetDpiY.

FUNCTION AfxLogPixelsY () AS LONG
FUNCTION AfxGetDpiY () AS LONG

AfxScaleRatioX

Retrieves the desktop horizontal scaling ratio.

FUNCTION AfxScaleRatioX () AS LONG

AfxScaleRatioY

Retrieves the desktop vertical scaling ratio.

FUNCTION AfxScaleRatioY () AS LONG

AfxScaleX

Scales an horizontal coordinate according the DPI (dots per pixel) being used by the operating system.

FUNCTION AfxScaleX (BYVAL cx AS SINGLE) AS SINGLE

Return value

The scaled coordinate.

AfxScaleY

Scales a vertical coordinate according the DPI (dots per pixel) being used by the operating system.

FUNCTION AfxScaleY (BYVAL cx AS SINGLE) AS SINGLE

Return value

The scaled coordinate.

AfxSetProcessDPIAware

Sets the current process as dots per inch (dpi) aware.

Note: AfxSetProcessDPIAware is subject to a possible race condition if a DLL caches dpi settings during initialization. For this reason, it is recommended that dpi-aware be set through the application (.exe) manifest rather than by calling AfxSetProcessDPIAware.

FUNCTION AfxSetProcessDPIAware () AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE. Otherwise, the return value is FALSE.

Remarks

DLLs should accept the dpi setting of the host process rather than call AfxSetProcessDPIAware themselves. To be set properly, dpiAware should be specified as part of the application (.exe) manifest. (dpiAware defined in an embedded DLL manifest has no affect.) The following markup shows how to set dpiAware as part of an application (.exe) manifest.

<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0" xmlns:asmv3="urn:schemas-microsoft-com:asm.v3" >
 ...
  <asmv3:application>
    <asmv3:windowsSettings xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">
      <dpiAware>true</dpiAware>
    </asmv3:windowsSettings>
  </asmv3:application>
 ...
</assembly>

AfxUnscaleX

Unscales an horizontal coordinate according the DPI (dots per pixel) being used by the operating system.

FUNCTION AfxUnscaleX (BYVAL cx AS SINGLE) AS SINGLE

Return value

The unscaled coordinate.

AfxUnscaleY

Unscales a vertical coordinate according the DPI (dots per pixel) being used by the operating system.

FUNCTION AfxUnscaleY (BYVAL cx AS SINGLE) AS SINGLE

Return value

The unscaled coordinate.

AfxUseDpiScaling

Returns TRUE if the OS uses DPI scaling; FALSE otherwise.

FUNCTION AfxUseDpiScaling () AS BOOLEAN

AfxCreateFont

Creates a logical font.

FUNCTION AfxCreateFont (BYREF wszFaceName AS WSTRING, BYVAL lPointSize AS LONG, BYVAL DPI AS LONG = 96, _
   BYVAL lWeight AS LONG = 0, BYVAL bItalic AS UBYTE = FALSE, BYVAL bUnderline AS UBYTE = FALSE, _
   BYVAL bStrikeOut AS UBYTE = FALSE, BYVAL bCharSet AS UBYTE = DEFAULT_CHARSET) AS HFONT

Return value

The handle of the font or NULL on failure.

Remarks

The returned font must be destroyed with DeleteObject or the macro DeleteFont when no longer needed to prevent memory leaks.

Usage examples

hFont = AfxCreateFont("MS Sans Serif", 8, , FW_NORMAL, , , , DEFAULT_CHARSET)
hFont = AfxCreateFont("Courier New", 10, 96 , FW_BOLD, , , , DEFAULT_CHARSET)
hFont = AfxCreateFont("Marlett", 8, -1, FW_NORMAL, , , , SYMBOL_CHARSET)

AfxGetFontHeight

Returns the logical height of a font given its point size.

FUNCTION AfxGetFontHeight (BYVAL nPointSize AS LONG) AS LONG

AfxGetFontPointSize

Returns the point size of a font given its logical height.

FUNCTION AfxGetFontPointSize (BYVAL nHeight AS LONG) AS LONG

AfxGetWindowFont

Retrieves the font with which the window or control is currently drawing its text.

FUNCTION AfxGetWindowFont (BYVAL hwnd AS HWND) AS HFONT

Return value

The handle of the font.

AfxGetWindowFontInfo

Retrieves information about the font being used by a window or control.

FUNCTION AfxGetWindowFontInfo (BYVAL hwnd AS HWND) AS LOGFONTW

Return value

A LOGFONTW structure.

AfxGetWindowsFontInfo

Retrieves information about the fonts used by Windows.

FUNCTION AfxGetWindowsFontInfo (BYVAL nType AS LONG, BYVAL plfw AS LOGFONTW PTR) AS BOOLEAN

Return value

TRUE on succes or FALSE on failure. To get extended error information, call GetLastError.

AfxGetWindowsFontPointSize

Retrieves the point size of the fonts used by Windows.

FUNCTION AfxGetWindowsFontPointSize (BYVAL nType AS LONG) AS LONG

AfxModifyFontFaceName

Modifies the face name of the font of a window or control.

FUNCTION AfxModifyFontFaceName (BYVAL hwnd AS HWND, BYREF wszNewFaceName AS WSTRING) AS HFONT

Return value

The handle of the new font on success, or NULL on failure.

To get extended error information call GetLastError.

Remarks

The returned font must be destroyed with DeleteObject or the macro DeleteFont when no longer needed to prevent memory leaks.

AfxModifyFontHeight

Modifies the height of the font used by a window of control.

FUNCTION AfxModifyFontHeight (BYVAL hwnd AS HWND, BYVAL nValue AS LONG) AS HFONT

Return value

The handle of the new font on success, or NULL on failure.

To get extended error information call GetLastError.

Remarks

The returned font must be destroyed with DeleteObject or the macro DeleteFont when no longer needed to prevent memory leaks.

AfxModifyFontSettings

Modifies settings of the font used by a window of control.

FUNCTION AfxModifyFontSettings (BYVAL hwnd AS HWND, BYVAL nSetting AS LONG, BYVAL nValue AS LONG) AS HFONT

Return value

The handle of the new font on success, or NULL on failure.

To get extended error information call GetLastError.

Remarks

The returned font must be destroyed with DeleteObject or the macro DeleteFont when no longer needed to prevent memory leaks.

AfxSetWindowFont

Sets the font that a control is to use when drawing text.

SUB AfxSetWindowFont (BYVAL hwnd AS HWND, BYVAL hFont AS HFONT, BYVAL fRedraw AS LONG = CTRUE)

Return value

The handle of the new font on success, or NULL on failure.

To get extended error information call GetLastError.

Remarks

The application should call the DeleteObject function to delete the font when it is no longer needed; for example, after it destroys the control.

The size of the control does not change as a result of receiving this message. To avoid clipping text that does not fit within the boundaries of the control, the application should correct the size of the control window before it sets the font.

AfxClearClipboard

Clears the contents of the clipboard.

FUNCTION AfxClearClipboard () AS LONG

Return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

AfxGetClipboardData

Retrieves data from the clipboard in the specified format.

FUNCTION AfxGetClipboardData (BYVAL cfFormat AS DWORD) AS HGLOBAL

Standard clipboard formats:

Return value

If the function succeeds, the return value is the handle to the data. If the function fails, the return value is NULL.

AfxGetClipboardText

Returns a text string from the clipboard.

FUNCTION AfxGetClipboardText () AS DWSTRING

Return value

The retrieved text string.

AfxSetClipboardData

Places data on the clipboard in a specified clipboard format.

FUNCTION AfxSetClipboardData (BYVAL cfFormat AS DWORD, BYVAL hData AS HANDLE) AS HANDLE

Standard clipboard formats:

Return value

If the function succeeds, the return value is the handle to the data. If the function fails, the return value is NULL.

Remarks

If AfxSetClipboardData succeeds, the system owns the object identified by the hData parameter. The application may not write to or free the data once ownership has been transferred to the system.

AfxSetClipboardText

Places a text string into the clipboard.

FUNCTION AfxSetClipboardText (BYREF wszText AS WSTRING) AS HANDLE

Return value

If the function succeeds, the return value is the handle to the data. If the function fails, the return value is NULL.

AfxCaptureDisplay

Captures the display and returns an handle to a bitmap.

FUNCTION AfxCaptureDisplay () AS HBITMAP

Return value

The handle of a bitmap.

Usage example

DIM hBitmap AS HBITMAP = AfxCaptureDisplay

AfxGetBitmapHeight

Retrieves the height of the specified bitmap.

FUNCTION AfxGetBitmapHeight (BYVAL hBitmap AS HBITMAP) AS LONG

Return value

The height of the bitmap on success or 0 on failure.

AfxGetBitmapWidth

Retrieves the width of the specified bitmap.

FUNCTION AfxGetBitmapWidth (BYVAL hBitmap AS HBITMAP) AS LONG

Return value

The width of the bitmap on success or 0 on failure.

AfxCreateDIBSection

Creates a DIB section.

FUNCTION AfxCreateDIBSection (BYVAL hdc AS HDC, BYVAL nWidth AS DWORD, BYVAL nHeight AS DWORD, _
   BYVAL bpp AS LONG = 0, BYVAL ppvBits AS ANY PTR PTR = NULL) AS HBITMAP

Return value

If the function succeeds, the return value is a handle to the newly created DIB, and ppvBits points to the bitmap bit values.

If the function fails, the return value is NULL, and ppvBits is NULL. The function can fail if one or more of the input parameters is invalid.

This function can return the following value: ERROR_INVALID_PARAMETER (One or more of the input parameters is invalid).

Remarks

You must delete the returned bitmap handle with DeleteObject when no longer needed to avoid memory leaks.

You cannot paste a DIB section from one application into another application.

AfxCreateDIBSection does not use the BITMAPINFOHEADER parameters biXPelsPerMeter or biYPelsPerMeter and will not provide resolution information in the BITMAPINFO structure.

Usage example

DIM hdcWindow AS HDC, hbmp AS HBITMAP, pvBits AS ANY PTR
hdcWindow = GetWindowDC(hwnd)   ' where hwnd is the handle of the wanted window or control
hbmp = AfxCreateDIBSection(hdcWindow, 10, 10, @pvBits)
ReleaseDC(hwnd, hdcWindow)

AfxCenterWindow

Centers a window on the screen or over another window. It also ensures that the placement is done within the work area.

SUB AfxCenterWindow (BYVAL hwnd AS HWND = NULL, BYVAL hwndParent AS HWND = NULL)

AfxForceSetForegroundWindow

Brings the thread that created the specified window into the foreground and activates the window. Keyboard input is directed to the window, and various visual cues are changed for the user. The system assigns a slightly higher priority to the thread that created the foreground window than it does to other threads.

SUB AfxForceSetForegroundWindow (BYVAL hwnd AS HWND)

Remarks

Replacement for the SetForegroundWindow API function, that sometimes fails.

AfxGetSystemInfo

Retrieves information about the current system.

FUNCTION AfxGetSystemInfo (BYREF metricName AS STRING) AS LONG_PTR

AfxGetTopEnabledWindow

Retrieves the handle of the enabled and visible window at the top of the z-order in an application.

FUNCTION AfxGetTopEnabledWindow () AS HWND

Return value

Handle of the window at top of z-order or NULL.

AfxGetTopLevelParent

Retrieves the window’s top-level parent window.

FUNCTION AfxGetTopEnabledWindow () AS HWND

Return value

Handle of the top-level parent window.

AfxGetTopLevelWindow

Retrieves the window’s top-level parent or owner window.

FUNCTION AfxGetTopLevelWindow (BYVAL hwnd AS HWND) AS HWND

Return value

Handle of the top-level parent or owner window.

AfxGetWindowBounds

Retrieves the bounds of a window without the drop shadows.

FUNCTION AfxGetWindowBounds (BYVAL hWin AS HWND) AS RECT

Remarks

In Windows Vista and later, the Window Rect includes the area occupied by the drop shadow. Calling GetWindowRect will have different behavior depending on whether the window has ever been shown or not. If the window has not been shown before, GetWindowRect will not include the area of the drop shadow. To get the window bounds excluding the drop shadow, use DwmGetWindowAttribute, specifying DWMWA_EXTENDED_FRAME_BOUNDS. Note that unlike the Window Rect, the DWM Extended Frame Bounds are not adjusted for DPI. Getting the extended frame bounds can only be done after the window has been shown at least once.

AfxGetWindowClassName

Retrieves the name of the class to which the specified window belongs.

FUNCTION AfxGetWindowClassName (BYVAL hwnd AS HWND) AS DWSTRING

Return value

The name of the class.

AfxGetWindowClientHeight

Returns the height of the client area of window, in pixels.

FUNCTION AfxGetWindowClientHeight (BYVAL hwnd AS HWND) AS LONG

AfxGetWindowClientRect

Retrieves the coordinates of a window’s client area. The client coordinates specify the upper-left and lower-right corners of the client area. Because client coordinates are relative to the upper-left corner of a window’s client area, the coordinates of the upper-left corner are (0,0).

FUNCTION AfxGetWindowClientRect (BYVAL hwnd AS HWND) AS RECT

Return value

A RECT structure with the retrieved coordinates of the window’s client area.

AfxGetWindowClientWidth

Returns the width of the client area of a window, in pixels.

FUNCTION AfxGetWindowClientWidth (BYVAL hwnd AS HWND) AS LONG

AfxGetWindowHeight

Returns the height of a window, in pixels.

FUNCTION AfxGetWindowHeight (BYVAL hwnd AS HWND) AS LONG

AfxGetWindowLocation

Returns the location of the top left corner of the window, in pixels. The location is relative to the upper-left corner of the client area in the parent window.

SUB AfxGetWindowLocation (BYVAL hwnd AS HWND, BYREF nLeft AS LONG, BYREF nTop AS LONG)

AfxGetWindowRect

Retrieves the dimensions of the bounding rectangle of the specified window. The dimensions are given in screen coordinates that are relative to the upper-left corner of the screen.

FUNCTION AfxGetWindowRect (BYVAL hwnd AS HWND) AS RECT

Return value

A RECT structure with the retrieved dimensions.

AfxGetWindowSize

Gets the width and height of the specified window, in pixels.

FUNCTION AfxGetWindowSize (BYVAL hwnd AS HWND, BYVAL nWidth AS LONG, BYVAL nHeight AS LONG) AS BOOLEAN

AfxGetWindowText

Gets the text of a window. This function can also be used to retrieve the text of buttons, edit and static controls.

FUNCTION AfxGetWindowText (BYVAL hwnd AS HWND) AS DWSTRING

Return value

The text of the window.

For an edit control, the text returned is the content of the edit control. For a combo box, the text is the content of the edit control (or static-text) portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title. To retrieve the text of an item in a list box, an application can use the ListBox_GetText function.

Rich Edit: If the text to be copied exceeds 64K, use either the EM_STREAMOUT or EM_GETSELTEXT message.

Remarks

This function uses the WM_GETTEXT message because GetWindowText cannot retrieve the text of a window in another application.

Usage examples

DIM dwsText AS DWSTRING = AfxGetWindowText(hwnd) MessageBoxW 0, dwsText, ““, MB_OK

AfxGetWindowTextLength

Retrieves the length of the text of a window. This function can also be used to retrieve the length of the text of buttons, edit and static controls.

FUNCTION AfxGetWindowTextLength (BYVAL hwnd AS HWND) AS LONG

Return value

If the function succeeds, the return value is the length of the text in characters, not including the terminating null character.

If the function fails, the return value is zero.

For an edit control, the text returned is the content of the edit control. For a combo box, the text is the content of the edit control (or static-text) portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title. To retrieve the text of an item in a list box, an application can use the ListBox_GetTextLength function.

AfxGetWindowTextLength sends a WM_GETTEXTLENGTH message. When the WM_GETTEXTLENGTH message is sent, the DefWindowProc function returns the length, in characters, of the text. Under certain conditions, the DefWindowProc function returns a value that is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the system allowing for the possible existence of double-byte character set (DBCS) characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode.

To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function.

Sending a WM_GETTEXTLENGTH message to a non-text static control, such as a static bitmap or static icon control, does not return a string value. Instead, it returns zero.

AfxGetWindowWidth

Returns the width of a window, in pixels.

FUNCTION AfxGetWindowWidth (BYVAL hwnd AS HWND) AS LONG

AfxGetWorkAreaHeight

Retrieves the height of the work area on the primary display monitor expressed in virtual screen coordinates. The work area is the portion of the screen not obscured by the system taskbar or by application desktop toolbars. To get the work area of a monitor other than the primary display monitor, call the GetMonitorInfo function.

FUNCTION AfxGetWorkAreaHeight () AS LONG

AfxGetWorkAreaRect

Retrieves the coordinates of the work area on the primary display monitor expressed in virtual screen coordinates. The work area is the portion of the screen not obscured by the system taskbar or by application desktop toolbars. To get the work area of a monitor other than the primary display monitor, call the GetMonitorInfo function.

FUNCTION AfxGetWorkAreaRect () AS RECT

Return value

A RECT structure with the retrieved coordinates.

AfxGetWorkAreaWidth

Retrieves the width of the work area on the primary display monitor expressed in virtual screen coordinates. The work area is the portion of the screen not obscured by the system taskbar or by application desktop toolbars. To get the work area of a monitor other than the primary display monitor, call the GetMonitorInfo function.

FUNCTION AfxGetWorkAreaWidth () AS LONG

AfxRedrawNonClientArea

Redraws the non-client area of the specified window.

FUNCTION AfxRedrawNonClientArea (BYVAL hwnd AS HWND) AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

AfxMoveWindowForDpi

Changes the position and dimensions of the specified window. For a top-level window, the position and dimensions are relative to the upper-left corner of the screen. For a child window, they are relative to the upper-left corner of the parent window’s client area. DPI aware versiomn of the API function MoveWindow.

PRIVATE FUNCTION AfxMoveWindowForDPI (BYVAL hwnd AS HWND, BYVAL x AS LONG, BYVAL y AS LONG, _
   BYVAL nWidth AS LONG, BYVAL nHeight AS LONG, BYVAL bRepaint AS BOOLEAN = TRUE) AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

If the bRepaint parameter is TRUE, the system sends the WM_PAINT message to the window procedure immediately after moving the window (that is, the MoveWindow function calls the UpdateWindow function). If bRepaint is FALSE, the application must explicitly invalidate or redraw any parts of the window and parent window that need redrawing.

MoveWindow sends the WM_WINDOWPOSCHANGING, WM_WINDOWPOSCHANGED, WM_MOVE, WM_SIZE, and WM_NCCALCSIZE messages to the window.

AfxRedrawWindow

Redraws the specified window.

SUB AfxRedrawWindow (BYVAL hwnd AS HWND)

AfxSetWindowClientSize

Adjusts the bounding rectangle of a window based on the desired size of the client area.

SUB AfxSetWindowClientSize (BYVAL hwnd AS HWND, BYVAL nWidth AS LONG, BYVAL nHeight AS LONG, _
   BYVAL rxRatio AS SINGLE = 1, BYVAL ryRatio AS SINGLE = 1)
SUB AfxSetWindowClientSizeForDpi (BYVAL hwnd AS HWND, BYVAL nWidth AS LONG, BYVAL nHeight AS LONG)

Remarks

AfxSetWindowClientSizeForDpi if DPI aware version of AfxSetWindowClientSizeFor.

AfxSetWindowIcon

Associates a new large icon with a window. The system displays the large icon in the ALT+TAB dialog box, and the small icon in the window caption.

FUNCTION AfxSetWindowIcon (BYVAL hwnd AS HWND, BYVAL nIconType AS LONG, BYVAL hIcon AS HICON) AS HICON

Return value

The return value is a handle to the previous large or small icon, depending on the value of nIconType. It is NULL if the window previously had no icon of the type indicated by nIconType.

AfxSetWindowLocation

Sets the location of the top left corner of the window, in pixels.The location is relative to the upper-left corner of the client area in the parent window.

FUNCTION AfxSetWindowLocation (BYVAL hwnd AS HWND, BYVAL nLeft AS LONG, BYVAL nTop AS LONG) AS BOOLEAN
FUNCTION AfxSetWindowLocationForDpi (BYVAL hwnd AS HWND, BYVAL nLeft AS LONG, BYVAL nTop AS LONG) AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

AfxSetWindowLocationForDpi is a DPI awre version of AfxSetWindowLocation.

AfxSetWindowPosForDpi

Changes the size, position, and Z order of a child, pop-up, or top-level window. DPI aware version of the API function SetWindowPos.

PRIVATE FUNCTION AfxSetWindowPosForDPI (BYVAL hwnd AS HWND, BYVAL hWndInsertAfter AS HWND, _
   BYVAL x AS LONG, BYVAL y AS LONG, BYVAL cx AS LONG, BYVAL cy AS LONG, _
   BYVAL uFlags AS UINT = SWP_NOZORDER) AS BOOLEAN

AfxSetWindowSize

Sets the size of the specified window, in pixels.

FUNCTION AfxSetWindowSize (BYVAL hwnd AS HWND, BYVAL nWidth AS LONG, BYVAL nHeight AS LONG) AS BOOLEAN
FUNCTION AfxSetWindowSizeForDpi (BYVAL hwnd AS HWND, BYVAL nWidth AS LONG, BYVAL nHeight AS LONG) AS BOOLEAN

Remarks

AfxSetWindowSizeForDpi is a DPI aware version of AfxSetWindowSize.

AfxSetWindowText

Sets the text of a window. This function can also be used to set the text of buttons, edit and static controls.

FUNCTION AfxSetWindowText (BYVAL hwnd AS HWND, BYVAL pwszText AS WSTRING PTR) AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

AfxShowWindowState

Sets the specified window’s show state.

FUNCTION AfxShowWindowState (BYVAL hwnd AS HWND, BYVAL nShowState AS LONG) AS BOOLEAN

Return value

If the window was previously visible, the return value is TRUE.

If the window was previously hidden, the return value is FALSE.

Remarks

To perform certain special effects when showing or hiding a window, use AnimateWindow.

The first time an application calls AfxShowWindowState, it should use the WinMain function’s nCmdShow parameter as its nCmdShow parameter. Subsequent calls to AfxShowWindowState must use one of the values in the given list, instead of the one specified by the WinMain function’s nCmdShow parameter.

As noted in the discussion of the nCmdShow parameter, the nCmdShow value is ignored in the first call to AfxShowWindowState if the program that launched the application specifies startup information in the structure. In this case, AfxShowWindowState uses the information specified in the STARTUPINFO structure to show the window. On subsequent calls, the application must call AfxShowWindowState with nCmdShow set to SW_SHOWDEFAULT to use the startup information provided by the program that launched the application. This behavior is designed for the following situations:

• Applications create their main window by calling CreateWindow with the WS_VISIBLE flag set.
• Applications create their main window by calling CreateWindow with the WS_VISIBLE flag cleared, and later call AfxShowWindowState with the SW_SHOW flag set to make it visible.

AfxWindowsVersion

Returns the Windows version.

FUNCTION AfxWindowsVersion () AS LONG

Return value

Platform 1:

  400 Windows 95
  410 Windows 98
  490 Windows ME

Platform 2:

  400 Windows NT
  500 Windows 2000
  501 Windows XP
  502 Windows Server 2003
  600 Windows Vista and Windows Server 2008
  601 Windows 7
  602 Windows 8
  603 Windows 8.1
 1000 Windows 10

Note 1: As Windows 95 and Windows NT return the same version number, we also need to call AfxGetWindowsPlatform to differentiate them.

Note 2: As Windows 10 and Windows 11 return the same version number, we also need to call AfxWindowsBuild to differentiate them. Windows 11 is Windows 10 build 21996 and higher.

Alias

AfxGetWindowsVersion

AfxWindowsMajorVersion

Returns the Windows major version.

FUNCTION AfxWindowsMajorVersion () AS LONG

Alias

AfxGetWindowsMajorVersion

AfxWindowsMinorVersion

Returns the Windows minor version.

FUNCTION AfxWindowsMinorVersion () AS LONG

Alias

AfxGetWindowsMinorVersion

AfxWindowsVersionStr

Returns the full Windows version, including the build number, as a string.

FUNCTION AfxWindowsVersionStr () AS DWSTRING

Alias

AfxGetWindowsVersionStr

AfxProcessorArchitecture

Returns the processor architecture of the operating system, e.g. “AMD64”.

FUNCTION AfxProcessorArchitecture () AS DWSTRING

AfxProcessorsCount

Returns the number of processors.

FUNCTION AfxProcessorsCount () AS LONG

AfxTotalPageFile

Returns the current committed memory limit for the system or the current process, whichever is smaller, in bytes.

FUNCTION AfxTotalPageFile () AS DWORDLONG

AfxAvailablePageFile

Returns maximum amount of memory the current process can commit, in bytes. This value is equal to or smaller than the system-wide available commit value.

FUNCTION AfxAvailablePageFile () AS DWORDLONG

AfxWindowsBuild

Returns the Windows build number.

FUNCTION AfxWindowsBuild () AS LONG

Alias

AfxGetWindowsBuild

AfxWindowsInstallDate

Returns the date in which Windows was installed, in Unix time.

FUNCTION AfxWindowsInstallDate () AS DWORD

Alias

AfxGetWindowsInstallDate

Usage examples:

PRINT AfxUnixDateStr(AfxWindowsInstallDate, "dd-MM-yyyy")
PRINT AfxUnixTimeStr(AfxWindowsInstallDate, "hh':'mm':'ss")

AfxAppsUseDarkMode

Returns TRUE if Windows applications are using dark mode, or FALSE otherwise.

FUNCTION AfxAppsUseDarkMode () AS BOOLEAN

AfxSystemUsesDarkMode

Returns TRUE if Windows is using dark mode, or FALSE otherwise.

FUNCTION AfxSystemUseDarkMode () AS BOOLEAN

AfxWindowsPlatform

Returns the Windows platform.

FUNCTION AfxWindowsPlatform () AS LONG

Return value

Alias

AfxGetWindowsPlatform

AfxWindowsBitness

Returns the Windows bitness (32 or 64 bit).

FUNCTION AfxWindowsBitness () AS LONG

AfxIsPlatformNT

Returns TRUE if the Windows Platform is NT; FALSE, otherwise.

FUNCTION AfxIsPlatformNT () AS BOOLEAN

AfxWindowsFeatureUpdate

Returns the Windows feature update versión, e.g. 22H2.

FUNCTION AfxWindowsFeatureUpdate () AS DWSTRING

AfxComCtlVersion

Returns the version of CommCtl32.dll

#define AfxComCtlVersion AfxGetFileVersion("COMCTL32.DLL")

Return value

The version of CommCtl32.dll multiplied by 100, e.g. 582 for version 5.82.

AfxMsg

Displays an application modal message box. Can be used with any string data type or literal.It is a quick shortcur for the MessageBoxW API function.

FUNCTION AfxMsg (BYREF wszText AS WSTRING, BYREF wszCaption AS WSTRING = "Message", _
   BYVAL uType AS DWORD = 0) AS LONG
FUNCTION AfxMsg (BYVAL pwszText AS WSTRING PTR, BYREF wszCaption AS WSTRING = "Message", _
   BYVAL uType AS DWORD = 0) AS LONG
FUNCTION AfxMsg (BYVAL hWin AS HWND, BYREF wszText AS WSTRING, BYREF wszCaption AS WSTRING = "Message", _
   BYVAL uType AS DWORD = 0) AS LONG
FUNCTION AfxMsg (BYVAL hWin AS HWND, BYVAL pwszText AS WSTRING PTR, BYREF wszCaption AS WSTRING = "Message", _
   BYVAL uType AS DWORD = 0) AS LONG

AfxGetWinDir

Retrieves the path of the Windows directory. This path does not end with a backslash unless the Windows directory is the root directory. For example, if the Windows directory is named Windows on drive C, the path of the Windows directory retrieved by this function is C:. If the system was installed in the root directory of drive C, the path retrieved is C:\.

FUNCTION AfxGetWinDir () AS DWSTRING

AfxGetWinErrMsg

Retrieves the localized description of the specified Windows error code.

FUNCTION AfxGetWinErrMsg (BYVAL dwError AS DWORD) AS DWSTRING

Return value

The localized description of the error code.

AfxGetComputerName

Retrieves the NetBIOS name of the local computer. This name is established at system startup, when the system reads it from the registry.

FUNCTION AfxGetComputerName () AS DWSTRING

Return value

The NetBIOS name of the local computer.

Alias

AfxComputerName

Remarks

The behavior of this function can be affected if the local computer is a node in a cluster. For more information, see ResUtilGetEnvironmentWithNetName and UseNetworkName.

AfxGetComputerNameDnsFullyQualified

Retrieves the fully qualified DNS name that uniquely identifies the local computer. This name is a combination of the DNS host name and the DNS domain name, using the form HostName.DomainName. If the local computer is a node in a cluster, dwsBuffer receives the fully qualified DNS name of the cluster virtual server.

FUNCTION AfxGetComputerNameDnsFullyQualified () AS DWSTRING

Alias

AfxComputerNameDnsHostname

AfxGetComputerNameDnsHostname

Retrieves the DNS host name of the local computer. If the local computer is a node in a cluster, dwsBuffer receives the DNS host name of the cluster virtual server.

FUNCTION AfxGetComputerNameDnsHostname () AS DWSTRING

Alias

AfxComputerNameDnsHostname

AfxGetComputerNameNetBIOS

Retrieves the NetBIOS name of the local computer. If the local computer is a node in a cluster, dwsBuffer receives the NetBIOS name of the cluster virtual server.

FUNCTION AfxGetComputerNameNetBIOS () AS DWSTRING

Alias

AfxComputerNameNetBIOS

AfxGetUserName

Retrieves the name of the user associated with the current thread.

FUNCTION AfxGetUserName () AS DWSTRING

Alias

AfxUserName

Return value

The name of the current user associated with the current thread.

Remarks

If the current thread is impersonating another client, the AfxGetUserName function returns the user name of the client that the thread is impersonating.

AfxGetUserDomain

Retrieves the name of the user associated with the current thread.

FUNCTION AfxGetUserDomain () AS DWSTRING

AfxGetPhysicallyInstalledSystemMemory

Retrieves the amount of RAM that is physically installed on the computer, in kilobytes.

FUNCTION AfxGetPhysicallyInstalledSystemMemory () AS ULONGLONG

Alias

AfxPhysicallyInstalledSystemMemory

AfxIsProcessElevated

Checks if the process is running with real administrative privileges.

FUNCTION AfxIsProcessElevated () AS BOOLEAN

AfxMemoryLoad

Returns the amount of actual physical memory, in bytes.

FUNCTION AfxMemoryLoad () AS DWORD

AfxTotalPhysicalMemory

Returns the amount of actual physical memory, in bytes.

FUNCTION AfxTotalPhysicalMemory () AS DWORDLONG

AfxAvailablePhysicalMemory

Returns the amount of physical memory currently available, in bytes. This is the amount of physical memory that can be immediately reused without having to write its contents to disk first. It is the sum of the size of the standby, free, and zero lists.

FUNCTION AfxTotalPhysicalMemory () AS DWORDLONG

AfxTotalVirtualMemory

Returns size of the user-mode portion of the virtual address space of the calling process, in bytes. This value depends on the type of process, the type of processor, and the configuration of the operating system. For example, this value is approximately 2 GB for most 32-bit processes on an x86 processor and approximately 3 GB for 32-bit processes that are large address aware running on a system with 4-gigabyte tuning enabled.

FUNCTION AfxTotalVirtualMemory () AS DWORDLONG

AfxAvailableVirtualMemory

Returns amount of unreserved and uncommitted memory currently in the user-mode portion of the virtual address space of the calling process, in bytes.

FUNCTION AfxAvailableVirtualMemory () AS DWORDLONG

AfxGetProductInfo

Retrieves the product type for the operating system on the local computer, and maps the type to the product types supported by the specified operating system.

FUNCTION AfxGetProductInfo () AS DWORD

Return value

Can be one of the following values (some products below may be out of support).

AfxGetMACAddress

Retrieves the MAC address of a machine’s Ethernet card.

FUNCTION AfxGetMACAddress () AS STRING

Return value

The MAC address in the following format: MM-MM-MM-SS-SS-SS. The leftmost 6 digits, called a “prefix”, is associated with the adapter manufacturer. The rightmost digits of a MAC address represent an identification number for the specific device.

Remarks

This function only supports one NIC card on your PC.

AfxGetMACAddressEx

Get the MAC address of the first valid physical adapter using GetAdaptersAddresses.

FUNCTION AfxGetMACAddress () AS STRING

Return value

The MAC address in the following format: MM-MM-MM-SS-SS-SS. The leftmost 6 digits, called a “prefix”, is associated with the adapter manufacturer. The rightmost digits of a MAC address represent an identification number for the specific device.

Remarks

This is the Microsoft-recommended method.

AfxGetAllMACAddresses

Populates a dynamic array of STRINGs with all the real MAC addresses of the system.

FUNCTION AfxGetAllMACAddresses (macs() AS STRING) AS LONG

Return value

The number of elements in the array or -1 on failure.

Usage example

DIM macs(ANY) AS STRING
DIM count AS LONG = AfxGetAllMACAddresses(macs())
FOR i AS LONG = LBOUND(macs) TO UBOUND(macs)
   PRINT macs(i)
NEXT

AfxGetAllPhysicalMACAddresses

Populates a dynamic array of STRINGs with all real MAC addresses (Ethernet/Wi-Fi).

FUNCTION AfxGetAllPhysicalMACAddresses (macs() AS STRING) AS LONG

Return value

The number of elements in the array or -1 on failure.

Usage example

DIM macs(ANY) AS STRING
DIM count AS LONG = AfxGetAllMACAddresses(macs())
FOR i AS LONG = LBOUND(macs) TO UBOUND(macs)
   PRINT macs(i)
NEXT

AfxGetDefaultBrowserPath

Retrieves the path of the default browser.

FUNCTION AfxGetDefaultBrowserPath () AS DWSTRING

Return value

The retrieved path or an empty string.

AfxGetDefaultMailClientName

Retrieves the name of the default client mail application.

FUNCTION AfxGetDefaultMailClientName () AS DWSTRING

Return value

The retrieved name or an empty string.

AfxGetDefaultMailClientPath

Retrieves the path of the default client mail application.

FUNCTION AfxGetDefaultMailClientPath () AS DWSTRING

Return value

The retrieved path or an empty string.

AfxGetInternetExplorerVersion

Returns the Internet Explorer version installed.

FUNCTION AfxGetInternetExplorerVersion () AS SINGLE

Return value

The Internet Explorer version (major.minor).

AfxInternetAttemptConnect

Attempts to make a connection to the Internet.

FUNCTION AfxInternetAttemptConnect () AS DWORD

Return value

Returns ERROR_SUCCESS if successful, or a system error code otherwise.

Remarks

This function allows an application to first attempt to connect before issuing any requests. A client program can use this to evoke the dial-up dialog box. If the attempt fails, the application should enter offline mode.

Like all other aspects of the WinINet API, this function cannot be safely called from within DllMain or the constructors and destructors of global objects.

Usage example

IF AfxInternetAttemptConnect = ERROR_SUCCESS THEN ? "You can connect to the Internet"

AfxInternetCheckConnection

Checks if a connection to the Internet can be established.

FUNCTION AfxInternetCheckConnection (BYVAL pwszUrl AS WSTRING PTR) AS BOOLEAN

Return value

Returns TRUE if a connection is made successfully, or FALSE otherwise. Use GetLastError to retrieve the error code. ERROR_NOT_CONNECTED is returned by GetLastError if a connection cannot be made or if the sockets database is unconditionally offline.

Remarks

InternetCheckConnection is deprecated. InternetCheckConnection does not work in environments that use a web proxy server to access the Internet. Depending on the environment, use NetworkInformation.GetInternetConnectionProfile or the NLM Interfaces to check for Internet access instead.

Usage example

IF AfxInternetCheckConnection("https://www.freebasic.net/forum/viewforum.php?f=1") THEN ? "Connection succeeded!"

AfxInternetCanonicalizeUrl

Canonicalizes a URL, which includes converting unsafe characters and spaces into escape sequences.

FUNCTION AfxInternetCanonicalizeUrl (BYVAL pwszUrl AS WSTRING PTR, BYVAL dwFlags AS DWORD = 0) AS DWSTRING

Return value

The canonicalized url on success or an empty string on failure.

Usage example

PRINT AfxInternetCanonicalizeUrl("http://msdn2.microsoft.com/en-us/ library/")

AfxInternetCombineUrl

Combines a base and relative URL into a single URL. The resultant URL is canonicalized.

FUNCTION AfxInternetCombineUrl (BYVAL pwszBaseUrl AS WSTRING PTR, BYVAL pwszRelativeUrl AS WSTRING PTR, _
   BYVAL dwFlags AS DWORD = 0) AS DWSTRING

Return value

The canonicalized url on success or an empty string on failure.

Usage example

PRINT AfxInternetCombineUrl (BYVAL pwszBaseUrl AS WSTRING PTR, BYVAL pwszRelativeUrl AS WSTRING PTR, _
   BYVAL dwFlags AS DWORD = 0) AS DWSTRING

AfxInternetGetConnectedState

Retrieves the connected state of the local system.

FUNCTION AfxInternetGetConnectedState () AS BOOLEAN

Return value

Returns TRUE or FALSE.

AfxInternetGetConnectionDescription

Retrieves the connection description.

FUNCTION AfxInternetGetConnectionDescription () AS DWORD

Return value

Can be a combination of the following values.

AfxInternetGetConnectionName

Retrieves the connection name.

FUNCTION AfxInternetGetConnectionDescription () AS DWORD

Return value

Returns the connection name on success or an empty string on failure.

AfxHiMetricToPixelsX

Converts from HiMetric to Pixels (horizontal resolution). Himetric is a scaling unit similar to twips used in computing. It is one thousandth of a centimeter and is independent of the screen resolution. HiMetric per inch = 2540; 1 inch = 2.54 mm.

SUB AfxHiMetricToPixelsX (BYVAL hm AS LONG) AS LONG

Return value

The size in pixels.

AfxHiMetricToPixelsY

Converts from HiMetric to Pixels (vertical resolution). Himetric is a scaling unit similar to twips used in computing. It is one thousandth of a centimeter and is independent of the screen resolution. HiMetric per inch = 2540; 1 inch = 2.54 mm.

SUB AfxHiMetricToPixelsY (BYVAL hm AS LONG) AS LONG

Return value

The size in pixels.

AfxPixelsToHiMetricX

Converts from Pixels to HiMetric (horizontal resolution). Himetric is a scaling unit similar to twips used in computing. It is one thousandth of a centimeter and is independent of the screen resolution. HiMetric per inch = 2540; 1 inch = 2.54 mm.

SUB AfxPixelsToHiMetricX (BYVAL cx AS LONG) AS LONG

Return value

The size in HiMetric units.

AfxPixelsToHiMetricY

Converts from Pixels to HiMetric (vertical resolution). Himetric is a scaling unit similar to twips used in computing. It is one thousandth of a centimeter and is independent of the screen resolution. HiMetric per inch = 2540; 1 inch = 2.54 mm.

SUB AfxPixelsToHiMetricY (BYVAL cx AS LONG) AS LONG

Return value

The size in HiMetric units.

AfxPixelsToPointsX

Converts pixels to points size (1/72 of an inch). Horizontal resolution.

SUB AfxPixelsToPointsX (BYVAL pix AS LONG) AS LONG

Return value

The number of points.

AfxPixelsToPointsY

Converts pixels to points size (1/72 of an inch). Vertical resolution.

SUB AfxPixelsToPointsY (BYVAL pix AS LONG) AS LONG

Return value

The number of points.

AfxPixelsToTwipsX

Converts pixels to twips. Horizontal resolution.

FUNCTION AfxPixelsToTwipsX (BYVAL nPixels AS LONG) AS LONG

Return value

The number of twips.

AfxPixelsToTwipsY

Converts pixels to twips. Vertical resolution.

FUNCTION AfxPixelsToTwipsY (BYVAL nPixels AS LONG) AS LONG

Return value

The number of twips.

AfxPointSizeToDip

Converts point size to DIP (device independent pixel). DIP is defined as 1/96 of an inch and a point is 1/72 of an inch.

FUNCTION AfxPointSizeToDip (BYVAL ptsize AS SINGLE) AS SINGLE

Return value

The number of DIP pixels.

AfxPointsToPixelsX

Converts a point size (1/72 of an inch) to pixels. Horizontal resolution.

FUNCTION AfxPointsToPixelsX (BYVAL pts AS LONG) AS LONG

Return value

The number of pixels.

AfxPointsToPixelsY

Converts a point size (1/72 of an inch) to pixels. Vertical resolution.

FUNCTION AfxPointsToPixelsY (BYVAL pts AS LONG) AS LONG

Return value

The number of pixels.

AfxTwipsPerPixelX

Returns the width of a pixel in twips (horizontal resolution). Pixel dimensions can vary between systems and may not always be square, so separate functions for pixel width and height are required.

FUNCTION AfxTwipsPerPixelX () AS LONG

Return value

The number of twips per pixel.

AfxTwipsPerPixelY

Returns the width of a pixel in twips (vertical resolution). Pixel dimensions can vary between systems and may not always be square, so separate functions for pixel width and height are required.

FUNCTION AfxTwipsPerPixelY () AS LONG

Return value

The number of twips per pixel.

AfxTwipsToPixelsX

Converts twips to pixels. Horizontal resolution.

FUNCTION AfxTwipsToPixelsX (BYVAL nTwips AS LONG) AS LONG

Return value

The number of pixels.

AfxTwipsToPixelsY

Converts twips to pixels. Vertical resolution.

FUNCTION AfxTwipsToPixelsY (BYVAL nTwips AS LONG) AS LONG

Return value

The number of pixels.

AfxDibLoadImage

Loads a DIB in memory and returns a pointer to it.

FUNCTION AfxDibLoadImage (BYVAL pwszFileName AS WSTRING PTR) AS BITMAPFILEHEADER PTR

Return value

A pointer to the bitmap file header. You must release it with CoTaskMemFree when no longer needed.

AfxDibSaveImage

Saves a DIB to a file.

FUNCTION AfxDibSaveImage (BYVAL pwszFileName AS WSTRING PTR, BYVAL pbmfh AS BITMAPFILEHEADER PTR) AS BOOLEAN

Return value

TRUE if the DIB has been saved successfully; FALSE otherwise.

AfxACLineStatus

Retrieves the AC power status.

FUNCTION AfxACLineStatus () AS UBYTE

Return value

This member can be one of the following values:

AfxBatteryChargeStatus

Retrieves the battery charge status.

FUNCTION AfxBatteryChargeStatus () AS UBYTE

Return value

Remarks

The value is zero if the battery is not being charged and the battery capacity is between low and high.

AfxBatteryLifePercent

The percentage of full battery charge remaining.

FUNCTION AfxBatteryLifePercent () AS UBYTE

Return value

This member can be a value in the range 0 to 100, or 255 if status is unknown.

AfxBatteryLifeTime

Retrieves the number of seconds of battery life remaining, or –1 if remaining seconds are unknown or if the device is connected to AC power.

FUNCTION AfxBatteryLifeTime () AS LONG

AfxBatteryFullLifeTime

Retrieves the number of seconds of battery life when at full charge, or –1 if full battery lifetime is unknown or if the device is connected to AC power.

FUNCTION AfxBatteryFullLifeTime () AS LONG

Remarks

The system is only capable of estimating BatteryFullLifeTime based on calculations on BatteryLifeTime and BatteryLifePercent. Without smart battery subsystems, this value may not be accurate enough to be useful.